HR - Employees - REST API

This operation allows to send Employee data to CODEX / CHECK and other applications (like Taliris).

REQUEST

url: /rest/v2/hr/employee

body: JSON format, containing all fields as below

Here is the format of the body that you should send:

{
  "HEADER":{
    "CORRELATION_ID": {technical ID used during all the transaction},
    "COMPANY_CODE": {ROC company code},
    "ANALYTICAL_CODE": {ROC BU code},
    "REQUEST_DATE_TIME": {datetime when the message is sent},
    "SOURCE_SYSTEM": {name of the source system},
    "TARGET_SYSTEM": {fixed value "DALI"},
    "TRANSACTION_ID": {functional identifier},
    "FLOW_NAME": {fixed value "EMPLOYEE"},
    "DISPATCHING_KEY": {empty}
  },
  "PAYLOAD":{
    "EMPLOYEES":{
      "EMPLOYEE":{
        "EMPLOYEE_HEADER":{
          "EMPLOYEE_ERP_ID": {personal number},
          "ERP_SOURCE": {'name of the source system'_'ISO code of the country'},
          "START_DATE": {start date of the occurrence format 'YYYY-MM-DD'},
          "END_DATE": {end date of the occurrence format 'YYYY-MM-DD'},
          "ACTION_REASON": {action reason},
          "ACTION_CATEGORY": {action category - codex only},
          "ID_VINCI": {Vinci ID},
          "ACTIVE": {active=1 / inactive=0},
          "CODEX_INDICATOR": {codex indicator - only used for an INIT},
          "UPDATE_DATE": {last update of the employee format 'YYYY-MM-DD hh:mm:ss'}
        },
        "PERSONAL":{
          "EMPLOYEE_AREA": {employee area - codex only},
          "EMPLOYEE_SUB_AREA": {employee subarea - codex only},
          "COST_CENTER": {cost center - codex only},
          "EMPLOYEE_GROUP": {employee group - codex only},
          "EMPLOYEE_SUB_GROUP": {employee subgroup - codex only},
          "EMPLOYEE_TYPE": {employee type - codex only},
          "PAYMENT_TYPE": {payment type - codex only},
          "SALARY": {salary - codex only},
          "VEHICULE_CLASS": {vehicle class - codex only},
          "TITLE": {employee's title : 1=Mr,Sir,M... / 2=Mrs,Miss,Lady...},
          "FIRST_NAME": {employee's first name},
          "BIRTH_NAME": {employee's birth name},
          "LAST_NAME": {employee's last name},
          "GENDER": {employee's gender : 1=male / 2=female},
          "SOCIAL_SECURITY_NUMBER": {social security number},
          "SOCIAL_SECURITY_KEY": {social security key},
          "NATIONALITY": {employee's nationality - ISO code on 3 characters},
          "BIRTH_DATE": {employee's birth date format 'YYYY-MM-DD'},
          "BIRTH_TOWN": {employee's birth town},
          "BIRTH_POSTAL_CODE": {employee's birth postal code},
          "BIRTH_STATE_CODE": {employee's birth state code},
          "BIRTH_COUNTRY_CODE": {employee's birth country code - ISO code on 3 characters},
          "ADRESSE_LINE1": {employee's address - limited to 10 characters in Codex},
          "ADRESSE_LINE2": {employee's address},
          "ADRESSE_LINE3": {employee's address},
          "ADRESSE_LINE4": {employee's address},
          "POSTAL_CODE": {employee's address zip code},
          "CITY_OR_TOWN": {employee's address town},
          "COUNTRY": {employee's address country - ISO code on 3 characters},
          "STATE": {employee's address state},
          "IBAN": {IBAN code - codex only},
          "BANK_COUNTRY_ISO_CODE": {country's ISO code on 2 characters - codex only},
          "EMPLOYEE_ADDON_FIELD":[
            {
              "EMPLOYEE_NO": {personal number - codex only},
              "EFFECT_DT": {effective date - codex only},
              "FIELD_TYPE": {field type - codex only},
              "FIELD_SUBTYPE": {field subtype - codex only},
              "FIELD_NAME": {field name - codex only},
              "FIELD_VALUE": {field value - codex only},
              "ADDON_FLAG": {flag - codex only}
            }
          ]
        },
        "PROFESSIONAL":{
          "GROUP_START_DATE": {start date in group format 'YYYY-MM-DD'},
          "OSMOSE_START_DATE": {start date in company format 'YYYY-MM-DD'},
          "SENIORITY_START_DATE": {start date in first arrival 'YYYY-MM-DD'},
          "ADRESSE_LINE1": {professionnal address},
          "ADRESSE_LINE2": {professionnal address},
          "ADRESSE_LINE3": {professionnal address},
          "ADRESSE_LINE4": {professionnal address},
          "POSTAL_CODE": {professionnal address postal code},
          "CITY_OR_TOWN": {professionnal address town},
          "COUNTRY": {professionnal address country},
          "STATE": {professionnal address state}
        },
        "MOVEMENT":[
          {
            "COMPANY_CODE": {ROC company code},
            "OSMOSE_CODE": {ROC osmose code},
            "BU_ANALYTIC_CODE": {ROC BU code},
            "JOB_TITLE": {local job title},
            "JOB_BUSINESS": {job business},
            "JOB_FAMILY": {job family},
            "ENTRY_CODE": {local entry code},
            "ENTRY_CATEGORY" : {local category of entry},
            "ENTRY_REASON" : {local reason of entry},
            "LEAVE_CODE": {local leave code},
            "LEAVE_CATEGORY" : {local category of exit},
            "LEAVE_REASON" : {local reason of exit}
          }
        ],
        "CONTRACT":[
          {
            "CONTRACT_END_DT": {empty - not used},
            "CONTRACT_NATURE": {contract nature},
            "CONTRACT_TYPE": {contract type},
            "ACTIVITY_PERCENTAGE": {activity percentage},
            "WORKING_DURATION_UNIT": {working duration unit},
            "WORKING_DURATION": {working duration}
          }
        ],
        "OCCUPATION":[
          {
            "CLASSIFICATION": {classification - socioprofessional category},
            "QUALIFICATION": {qualification},
            "POSITION": {position},
            "COLLECTIVE_AGREEMENT": {local collective agreement code},
            "GRADE": {conventional grade}
          }
        ],
        "EMPLOYE_ADDON":[
          {
            "SOURCE": {Source of the data},
            "EVENT_TYPE": {Type of the data},
            "EVENT_VALUE": {Value of the data},
            "START_DATE": {start date},
            "END_DATE": {end date},
            "UPDATE_DATE": {update date}
          }
        ]
      }
    }
  }
}

RESPONSE

Here is the format of the response we send:

{
  "ERROR": {
    "CODE": {error code},
    "DESCRIPTION": {error description},
    "DETAILS": {error details}
  }
}

Here are the different errors that we can send:

MAPPING

Here are further informations on each field:

APPENDIX EMPLOYEE

START DATE

This field must be initialized, as a YYYY-MM-DD format, in order to identify all changes of occurrences regarding the employee management.

E.g. :

• contract change, vehicle class, address, or others...
• hiring
• leaving

END DATE

This field must be initialized, as a YYYY-MM-DD format.

If there is no END_DATE defined for an employee, the date must be filled with 2999-12-31 value.

If the ACTION_REASON is LEA1, then the END_DATE MUST be equal to the real leaving date of the employee.

ACTION REASON

This field must be initialized in order to identify every management act regarding the employee.

E.g. :

• contract change, vehicle class, address, or others...
• hiring
• transfer (company)
• leaving

Here is an example of cases of modifications that can determine a management act:

• Employee with long term contract
  • Hiring
  • Change of section
  • Change of BU
  • Leaving
• Employee with short term contract
  • Hiring
  • Change of section
  • Change of BU
  • Change of type of contract from short term to long term
  • Leaving

Here are more details about each ACTION_REASON possible:

CODEX INDICATOR

Codex Value on one character, except for INIT.

ADDON FIELD

If there is an element into the table ADDON_FIELD (field_name, field_value), that exists in the base mapping, then the value of this element always prevails on the value of this field in the base mapping.

Example: In the base mapping, the field START_DATE equals the value 1988-05-01. I have an element in ADDON_FIELD table with a FIELD_NAME as BEGDA and a FIELD_VALUE as 2001-01-01. Then the concerned value will be 2001-01-01, and not 1998-05-01.

For some specifical requirements (TALIRIS, CHECK...), we will use a different rule than what is existing today for CODEX for the ADDON_FIELD part.

Below examples which CODEX will not be impacted, only used for CIM.

Add a value

Close a value

With the FIELD_TYPE = "CIM", sources* have the possibility to send :

• BU start date: when an employee is transferred into a new BU, the starting date into this BU can be sent using a specific add on field. This add on field is mandatory for HIR1 / HIR2 / MVT1 or TRA1 event.
• usual first and last name: It considers into CHECK only at the first employee hiring. After the hiring, the usual first/last name must be managed into CHECK.
• activity code: The code must be the code used into CHECK. WARNING: the user's rights are reset according to the code indicated.
• position in the organization: to precise the position for specific Job family / activity. This information is sent to CHECK
• first transversal role: to indicate if the employee has a transversal role (ex: PISO). This information is sent to CHECK
• second transversal role: to indicate if the employee has a second transversal role. This information is sent to CHECK

* sources : Actually, it’s only activated for DACH and Brazilian perimeters. If you would like to use the following add-on fields, please send us a request, which will be examined jointly with the Custom Apps team.

Possibles CIM add on fields:

"EMPLOYEE_ADDON_FIELD" : [
  {
    "EMPLOYEE_NO": "76669",
    "EFFECT_DT": "2025-07-01",
    "FIELD_TYPE": "CIM",
    "FIELD_SUBTYPE": "SAP_DE",
    "FIELD_NAME": "**BU_START_DATE**",
    "FIELD_VALUE": "2025-07-01",
    "ADDON_FLAG": ""
  },
  {
    "EMPLOYEE_NO": "76669",
    "EFFECT_DT": "2025-07-01",
    "FIELD_TYPE": "CIM",
    "FIELD_SUBTYPE": "SAP_DE",
    "FIELD_NAME": "**USUAL_FIRST_NAME**",
    "FIELD_VALUE": "Alfred Jean Philippe",
    "ADDON_FLAG": ""
  },
  {
    "EMPLOYEE_NO": "76669",
    "EFFECT_DT": "2025-07-01",
    "FIELD_TYPE": "CIM",
    "FIELD_SUBTYPE": "SAP_DE",
    "FIELD_NAME": "**USUAL_LAST_NAME**",
    "FIELD_VALUE": "DUPOND",
    "ADDON_FLAG": ""
  },
  {
    "EMPLOYEE_NO": "76669",
    "EFFECT_DT": "2025-07-01",
    "FIELD_TYPE": "CIM",
    "FIELD_SUBTYPE": "SAP_DE",
    "FIELD_NAME": "**ACTIVITY**",
    "FIELD_VALUE": "A81",
    "ADDON_FLAG": ""
  },
  {
    "EMPLOYEE_NO": "76669",
    "EFFECT_DT": "2025-07-01",
    "FIELD_TYPE": "CIM",
    "FIELD_SUBTYPE": "SAP_DE",
    "FIELD_NAME": "**ORGA_POSITION**",
    "FIELD_VALUE": "4",
    "ADDON_FLAG": ""
  },
  {
    "EMPLOYEE_NO": "76669",
    "EFFECT_DT": "2025-07-01",
    "FIELD_TYPE": "CIM",
    "FIELD_SUBTYPE": "SAP_DE",
    "FIELD_NAME": "**TRANSVERSAL_ROLE_1**",
    "FIELD_VALUE": "2",
    "ADDON_FLAG": ""
  },
  {
    "EMPLOYEE_NO": "76669",
    "EFFECT_DT": "2025-07-01",
    "FIELD_TYPE": "CIM",
    "FIELD_SUBTYPE": "SAP_DE",
    "FIELD_NAME": "**TRANSVERSAL_ROLE_2**",
    "FIELD_VALUE": "5",
    "ADDON_FLAG": ""
  }
]

EMPLOYEE_ADDON

This segment is used to send entry / exit reasons data.

Each item received for the employee will be integrated as long as it does not exist. That is, whenever there is data (source, type, value, start_date or end_date) that differs from an existing line.

Example:

"EMPLOYEE_ADDON " : [
  {
    "SOURCE": "HCP300",
    "EVENT_TYPE": "ENTRY_CODE",
    "EVENT_VALUE": "xxxx",
    "START_DATE": "2026-02-01",
    "END_DATE": "2999-12-31",
    "UPDATE_DATE": "2026-02-01 15:01:23",
  },
  {
    "SOURCE": "HCP300",
    "EVENT_TYPE": "ENTRY_CATEGORY",
    "EVENT_VALUE": "xxxx",
    "START_DATE": "2026-02-01",
    "END_DATE": "2999-12-31",
    "UPDATE_DATE": "2026-02-01 15:01:23",
  },
  {
    "SOURCE": "HCP300",
    "EVENT_TYPE": "ENTRY_REASON",
    "EVENT_VALUE": "xxxx",
    "START_DATE": "2026-02-01",
    "END_DATE": "2999-12-31",
    "UPDATE_DATE": "2026-02-01 15:01:23",
  }
]